# Light music player

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

The light music player is a multimedia demo project based on the Quectel Pi M2 smart single-board computer.  
This project plays local music files and analyses the audio signal in real time to drive a 16×16 WS2812 RGB full-color LED matrix display, producing lighting effects that change in sync with the music rhythm and linking the music with the lighting.

This project demonstrates the Quectel Pi M2's capabilities in audio processing, SPI peripheral control, and multi-threaded real-time display. It can serve as a reference example for applications such as music visualization, ambient lighting, and LED displays.

# Development resources summary

## Development accessories list

| **Accessory name** | **Quantity<br>(Unit: Pcs)** | **Specifications** |
| --- | --- | --- |
| Quectel Pi M2 smart single-board computer | 1 | - |
| 16×16 WS2812 RGB full-color LED matrix display | 1 | 16×16 WS2812 RGB full-color LED matrix display |
| PH1.25 2-pin interface speaker | 1 | [PH1.25 2-pin interface speaker](<https://www.amazon.com/DWEII-Rectangle-Electronic-Application-Components/dp/B0F3X3CF8G/ref=sr_1_1?crid=1UIN04BFXKI5W&dib=eyJ2IjoiMSJ9.MVXfU219fU74vmXX_a5f7qwTUoWu41WPsOLAjVl0sk6TBWaW8B5to0yVI4NK545AmnC_3N5TIrfi7cPJdXS56ewf56u7T1AJVDaSE0hL5tA8jHF8Rl8Ndlc8nQVMkNqPkiC56OfndEhOUk6QBisJqTu6H8TrgieGKA4C1g7hAXOqZLw5PQaz61oIdWy0QrQqr5Z1UvZur_co6z1IIWHGLco5ReO3tWTDWMP_8rH2SDc.srDfxjSCN9v--7WGt77JXA32UmOiZOHd8ZrlpBo-LF4&dib_tag=se&keywords=1.25mm+2+pin+speaker&qid=1763545864&sprefix=1.25mm+2+pin+speaker,aps,352&sr=8-1&th=1>) |
| Power adapter | 1 | [USB type-C power supply](<https://www.waveshare.com/product/raspberry-pi/accessories/raspberry-pi-45w-usb-c-power-supply.htm>) |
| HDMI A-type public connection line | 1 | HDMI 2.0; Length of the cable: 1 meter; Interface: HDMI-A (male connector) - HDMI-A (male connector) |
| Ethernet cable | 1 | Length: 1 m; Transmission rate: Gigabit |
| HDMI monitor | 1 | 24-inch HDMI monitor |

## Physical reference of accessories

```{image} images/image_FCBXbdAvRoqqufx972ecNHytnPb.webp
:width: 719px
:height: 426px
:align: center
```

# Get started quickly

## Development preparation

The Quectel Pi M2 smart single-board computer comes with the **Debian 13** system image pre-installed, so there is no need to flash the image again. Just follow the steps below.

## Hardware connection

### Peripheral connection

```{image} images/image_J8P8bFV0oorcTsxJwFgclv44nDb.webp
:width: 629px
:height: 437px
:align: center
```

1. **Display Connection:** Choose the connection method based on your monitor's interface. Here we use Option 2: connect one end of the Micro HDMI cable to the main board's Micro HDMI port and the other end to the monitor's HDMI port.  
    1. Option 1 (HD): Connect one end of the **FPC** ribbon cable to the **MIPI** port on the **Quectel Pi M2**, and the other end to the monitor's **MIPI** port. Refer to the [MIPI](<../../../User guide/Display/MIPI/MIPI.md>) for details.  
    1. Option 2 (Compatible): Connect one end of the **HDMI** cable to the **HDMI** port on the **Quectel Pi M2**, and the other end to the monitor's **HDMI** port.

2. **Network Connection**: Connect the **Quectel Pi M2** Ethernet port to the router's **LAN** port using an Ethernet cable.

3. **Peripheral Connection**: Plug the USB keyboard, mouse, and USB camera into the **USB-A** ports on the **Quectel Pi M2**. For wireless keyboard/mouse, simply plug the receiver into a **USB** port.

4. **Power Connection**: Finally, plug the **USB-A** end of the power cable into the power adapter, and the **USB-C** end into the power port on the **Quectel Pi M2**.

### 6×16 WS2812 connection

The 16×16 WS2812 RGB full-color LED matrix display is connected to the Quectel Pi M2 smart single-board computer through the **SPI**. Its data input end should connect to the corresponding pin on the Quectel Pi M2 (see the figure below for the wiring).

```{image} images/image_QiqJbrh1qoLE2rxz0KncWUePnCf.webp
:width: 726px
:height: 422px
:align: center
```

## Project implementation

### Prerequisites installation

After confirming that the device is connected to the network, open the terminal and run the following command:

```plaintext
sudo apt update && sudo apt install -y pulseaudio-utils python3-numpy python3-spidev ffmpeg
```

The command above updates the software sources and installs the libraries required to run the project, including:

- **pulseaudio-utils**: Provides audio utilities such as *pacat* to play decoded PCM audio data on the system;

- **python3-numpy**: Used for FFT spectrum analysis and numerical computation of audio signals, supporting spectrum-based lighting effects;

- **python3-spidev**: Enables Python access to the SPI interface, used to drive the WS2812 RGB full-color LED matrix display;

- **ffmpeg**: Decodes audio files such as files in MP3 and WAV format into a PCM data stream for audio playback and real-time analysis.

### Obtaining the code

Go to the [GitHub repository](<https://github.com/Quectel-Pi/demo-light-music-player>) to get the code and download it to the Quectel Pi M2. If you are accessing the device remotely, refer to [SCP file copy](<../../../User guide/Device connection/SCP file copy/SCP file copy.md>) for file transfer instructions.

### Preparing music files

Copy the music files (MP3 and WAV formats are supported) to the user's Music directory, such as */home/pi/Music*.

After the program starts, it automatically scans this directory for music files and generates a playlist.

# Application demo

## Running the program

Run the following commands in the project directory to start the program:

```plaintext
cd demo-light_music_player
sudo python3 light_music_player.py 
```

The lighting effect can be configured as *mode1* or *mode2*. After the program starts, it automatically plays music and displays lighting effects that change with the music rhythm on the 16×16 WS2812 RGB full-color LED matrix display.

After the program is running, the terminal shows the key controls (*n* for the next track, *u* for the previous track, *q* or *Ctrl+C* to exit the program).

```{image} images/image_VaMUbFWmzono5OxRucrcfe9unBh.webp
:width: 601px
:height: 69px
```

## Lighting effect description

**Notes: 16×16 WS2812 LED panel layout**

The physical wiring of the 16×16 WS2812 RGB full-color LED matrix display panel may differ between vendors. The panel used in this project is laid out as follows:

- **Starting LED position**: bottom-left corner (LED 0)

- **Direction of the first row**: left to right (LED 0 → LED 15)

- **Row direction**: bottom to top

- **Wiring pattern**: serpentine

In other words, the first row runs from left to right, the second row returns from right to left, and so on upward.

All lighting effects in the program (spectrum direction, raindrop direction, and so on) are mapped according to this layout.

If the panel you use is not wired as described above, the display may appear reversed or misaligned. In that case, adjust the LED matrix mapping configuration according to the actual wiring of the panel.

### **Spectrum push effect of mode1**

<div class="video-preview">
  <video width="100%" controls preload="none">
    <source src="videos/video_MfMJbZiMJoWHTaxAL0kcnqZKngb.mp4" type="video/mp4">
    Your browser does not support the video tag.
  </video>
  <div class="video-caption">
    <strong>1</strong>
  </div>
</div>


This mode is based on 16-band spectrum analysis of the audio:

- Each column of the LED matrix corresponds to the energy of one band;

- The bar height changes in real time with the spectrum energy;

- Supports smooth rising, slow falling, and peak-hold effects;

- When the music rhythm changes abruptly, the overall display produces a pronounced pushing visual effect.

### **Raindrop lighting effect of mode2**

<div class="video-preview">
  <video width="100%" controls preload="none">
    <source src="videos/video_MmdubGt9WoWcKyxBGwXcZMcknMg.mp4" type="video/mp4">
    Your browser does not support the video tag.
  </video>
  <div class="video-caption">
    <strong>2</strong>
  </div>
</div>


This mode simulates raindrops falling from the top of the display:

- The raindrop generation rate changes dynamically with the music intensity;

- Supports trailing effects and background color filling;

- The louder the volume, the denser the raindrops and the higher the brightness.

# Technical support and contributions

If you encounter any problems during use, please submit a technical inquiry on the [Quectel official forum](<https://forums.quectel.com/c/quectel-pi/80>). The Quectel technical support team will respond promptly.

Project open-source repository: [https://github.com/Quectel-Pi/demo-light-music-player](<https://github.com/Quectel-Pi/demo-light-music-player>)

You are welcome to submit issues to report problems or pull requests to contribute to code improvements!